Explain that unmap-event may never be emitted

Fixes: https://bugzilla.gnome.org/show_bug.cgi?id=613302

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index d20a5c9b318930de876c43ef67278b4f6e2709af..6cd6ba6250fcc69b6018f623b6881a3962b3a1bb 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1576,9 +1576,13 @@ gtk_widget_class_init (GtkWidgetClass *klass)
    * @widget: the object which received the signal
    * @event: the #GdkEventAny which triggered this signal
    *
-   * The ::unmap-event signal will be emitted when the @widget's window is
+   * The ::unmap-event signal may be emitted when the @widget's window is
    * unmapped. A window is unmapped when it becomes invisible on the screen.
    *
+   * For performance reasons GTK+ may not emit ::unmap-event, so one
+   * should always also implement ::unrealize in order to release
+   * resources and disconnect signal handlers.
+   *
    * To receive this signal, the #GdkWindow associated to the widget needs
    * to enable the #GDK_STRUCTURE_MASK mask. GDK will enable this mask
    * automatically for all new windows.